create or replace package m4o_output_advice as
  -- ===========================================================================
  -- out extends pl/sql by adding string embedding syntax like in pl/sql
  -- or java server pages. Expression values are embedded within "<%=...%>" and
  -- procedural pl/sql within "<%...%>". This extension is not only useful for
  -- HTML coding but works also for code generation in general.
  --
  -- out is automatically activated if the package part's source code
  -- starts with "<".
  --
  -- Attributes:
  -- * C_DISABLE_ATTR:
  --     out ignores the package part if this attribute is set.
  -- * C_GENERATOR_ATTR:
  --     It's value is the pl/sql code that is used to concatenate the text.
  --     Setting this attribute activates out.
  -- * C_V2_OUTPUT_ATTR:
  --     Activates out and uses C_V2_GENERATOR for text concatenation 
  --     unless C_GENERATOR_ATTR is set. Expects the varchar2 variable name
  --     as attribute value.
  -- * C_CLOB_OUTPUT_ATTR:
  --     Activates out and uses C_CLOB_GENERATOR for text concatenation 
  --     unless C_GENERATOR_ATTR is set. Expects the clob variable name as
  --     attribute value.
  -- * C_HTP_OUTPUT_ATTR:
  --     Activates out and uses C_HTP_GENERATOR fo text concatenation
  --     unless C_GENERATOR_ATTR is set. No attribute value.
  --     attribute value.
  --     Activates C_ESCAPE_FN_ATTR with C_HTP_ESCAPE_FN.
  -- * C_DBMS_OUTPUT_ATTR:
  --     Activates out and uses C_DBMS_GENERATOR fo text concatenation
  --     unless C_GENERATOR_ATTR is set. No attribute value.
  --     attribute value.
  -- * C_BUFFER_ATTR:
  --     Activates out and uses C_BUFFER_GENERATOR fo text concatenation
  --     unless C_GENERATOR_ATTR is set. No attribute value.
  --     attribute value.
  -- * C_LINESTART_ATTR:
  --     If it is set, out ignores characters from the beginning of a
  --     line up to the varchar2 in the attribute value (or C_DEFAULT_LINESTART,
  --     if no value is given).
  -- * C_ESCAPE_FN_ATTR:
  --     If it is set, code embedded with "<%" is escaped with this function.
  --     Code embedded with "<%%" is never escaped.
  --
  -- If out applies, it deactivates stringliteral_advice.
  -- ===========================================================================

  subtype attr_t       is m4o_package_attr.name%type;
  subtype generator_t  is varchar2(32767);
  subtype fn_t         is varchar2(32767);

  C_DISABLE_ATTR       constant attr_t := 'output.disable';
  C_GENERATOR_ATTR     constant attr_t := 'output.generator';
  C_V2_OUTPUT_ATTR     constant attr_t := 'output.to_v2';
  C_CLOB_OUTPUT_ATTR   constant attr_t := 'output.to_clob';
  C_HTP_OUTPUT_ATTR    constant attr_t := 'output.to_htp';
  C_DBMS_OUTPUT_ATTR   constant attr_t := 'output.to_dbms_output';
  C_BUFFER_OUTPUT_ATTR constant attr_t := 'output.to_buffer';
  C_LINESTART_ATTR     constant attr_t := 'output.linestart';
  C_ESCAPE_FN_ATTR     constant attr_t := 'output.escape_fn';

  C_V2_GENERATOR       constant generator_t := ':0:=:0||:1;';
  C_CLOB_GENERATOR     constant generator_t := 'm4o_v2.push(:0,:1,null);';
  C_HTP_GENERATOR      constant generator_t := 'sys.htp.p(:1);';
  C_DBMS_GENERATOR     constant generator_t := 'sys.dbms_output.put_line(:1);';
  C_BUFFER_GENERATOR   constant generator_t := ':0.p(:1);';

  C_HTP_ESCAPE_FN      constant fn_t := 'sys.htf.escape_sc(:0)';

  C_DEFAULT_LINESTART  constant varchar2(7) := '^[ 	]*%';

  -- ===========================================================================
  procedure apply_before_body_part(
    i_part in out nocopy m4o_package_generator.part_t);

end;
/

